User Guide

Golden Config is a configuration management tool based on a configuration tree. Designed to propagate root configurations to child nodes, it allows the user to write or copy native device configuration onto nodes (a single device or multiple devices). It also provides a compliance engine which enables the user to review and fix errors generated from mismatched configurations between the given config and the actual configuration on the attached device(s).

Note: The Itential Automation Platform (IAP) is compatible with several third-party software products for network operating environments. Beginning with the system requirements for 2019.1.2, all third-party software version compatibility is documented in Release Notes. To get the most up-to-date requirements for any third-party software, including open source, first identify which IAP release you’re using and then refer to the respective release note.

Installation Requirements

• To assign devices to the trees created in the application, setup devices and corresponding NEDs (network element drivers) in NSO.
• To install and configure services properly, follow documentation for Itential Prospector and itential_tools.

Prerequisites

See the Nexus registry for the package version bundled with your Itential Automation Platform release.

Package
adapter-prospector
itential_tools
Itential Prospector
itential-utils
Smart Template

Note: The Itential Prospector requirement is managed by adapter-prospector.

Application Interface

The main screen lists all existing configuration trees. If no configuration trees have been created, the list will be empty.

UI Label	Component	Description
1	New Tree	Create new configuration tree.
2	Tree list	List of existing configuration trees.
3	Edit tree	Edit existing configuration tree.
4	Run	Run compliance report.
5	View compliance report	Displays overview of tree with details about each node.

Configuration Trees

Use the following information to manage configuration trees.

Creating a New Tree

To create a new tree:

1. Click the NEW TREE button in the title bar of the main screen.
2. Enter a Tree Name in the Config Settings dialog.
3. Select a NED Type from the dropdown list.
4. Attach an existing IAP workflow (optional).
5. Click the CREATE button. A new empty Golden Configuration Tree with the root node is created.
   • You can edit and view this configuration tree just like any other existing configuration tree.

UI Label	Component	Description
1	Tree Variables	View and edit the tree variables.
2	Configure Tree	Update the tree settings.
3	Clone Tree	Make a copy of the tree.
4	Close	Return to the list of trees.
5	Tree Canvas	Edit nodes, add watchers, manage children, and view attached devices.

Editing a Tree

To edit a configuration tree:

1. Go to the Actions column (far right of main screen).
2. Click the Edit (pencil) icon . The Golden Configuration view opens. This allows you to view all created nodes and perform the following tasks:
   • Add new child node.
   • Remove child node.
   • Add Watcher Group.
   • Navigate to any node in the given tree.

Add Child Node

To add a new child node:

1. Click the blue plus sign next to the parent node.

Remove Child Node

To remove a child node:

1. Click the gray minus sign next to the child node you want to remove. Only leaf nodes can be removed.
2. If a node has children, the gray minus sign will not display.

Add Watcher Group

Use the following information to add a Watcher Group for workflows kicked off from a node.

1. Place your cursor over the node. A User icon will display in the upper left corner of the node graphic.
2. Click the User icon. The Add Watcher Groups dialog displays.
3. Select a user group from the Watcher Groups dropdown menu.
4. Click +ADD to select additional user groups.
5. Click SAVE.

Managing a Tree

Use the information in this section to distinguish tree levels, navigate through a tree, and configure nodes.

Navigation

Every tree level has a different color.

• The parent node is orange.
• The first level is blue.
• The second level is purple.

Configuring a Node

By clicking a node, you can:

• Rename the node using the input in the top left.
• Rename the entire tree by selecting the gear icon (top-right corner) and typing a new name.
• View, edit, and apply tree variables by selecting the variable icon {x} in the top-right corner.
• Clone the entire tree (root node and all child nodes, including configuration and attached devices) by selecting the copy icon (top-tight corner) and typing a new name for the cloned tree.
• Return to the tree view with View Tree.
• Return to the list with the close button (top-tight corner) .
• View, edit, and add configuration using the Config tab.
• View and run compliance reports using the Compliance tab.
• Attach and detach devices from the node using the Add Devices tab.

Configuration Tab

The Config tab on each node allows you to add a new configuration or edit an existing configuration.

Add New Configuration

To add a new configuration:

1. Select the ADD CONFIG button. A separate window opens.
2. Paste in native configuration. If there is an existing configuration on the node, the new config will merge with the existing configuration.
3. Click SUBMIT.

Configuration Levels

• Since configuration in each node follows a hierarchy, each node will inherit the configurations of its parent except where configurations of the child override those of the parent.
• A node will display only the parent configurations that it does not override.
• Optionally, the node can display the parent configurations or just the configuration on that specific node.
• Based on the node level, configurations are shown in their respective node color.
• If the node level is not the current level, it cannot be modified (unless it is overwritten by a new config on the current node).

Tree Variables

Tree variables can be used across any Golden Config tree. They can be set and updated using the variable icon {x} located in the top-right corner of the tool bar.

• Within the modal window, each variable includes a name, value and a type of comparison (either 'literal' or 'pattern').
• Each row can be deleted.
• Add more rows from the bottom of the table with the ( + ) button.

Using Tree Variables Inline

Configurations can accept substitutions for values from the tree variables. The variables will be able to be updated dynamically by the tree variable menu or the options menu.

• Variables are indicated by the name set in the tree variable menu.
• To use a tree variable as a value, type the variable name using the template brackets: ${variable}.
• Tree variables are automatically set and updated if a value matches a tree variable from the menu.

Configuration Operations and Options

Configurations have special operations available for use:

• Must Exist / Can't Exist
• Delete / Update

Must Exist / Can't Exist (Operation)

Operation	Description
Must Exist (default)	The configuration must include the specified item. The Must Exist operation is signified by a grayed out circle icon with a line through it.
Can't Exist	The configuration must not include the specified item. The Can't Exist operation is signified by a red circle icon with a line through it and a line through the configuration.

Delete / Update (Operation)

Operation	Description
Delete	Removes the specified item and all of its children. The Delete operation is signified by a Delete icon on the farthest right side of a listed configuration.
Update	Changes the value of the specified leaf. It automatically saves as you type. The Update operation is signified by a textbox area around values that you can edit or modify.

Configuration Options

To set configuration options:

1. Click the gray gear icon to the right of the configuration. The options dialog opens.
2. View the configuration Type (leaf).
3. Select the Severity of the Config Compliance from the dropdown menu.

1. If the value matches a Tree Variable, all values are hidden until No Variables is selected.
2. Select a Comparison type for the configuration (String or Regex).
3. Enter a configuration Value.
4. Optionally, on elements that are not keys, enter a Workflow Template Variable to override the value in a workflow.
5. Click the SUBMIT button.

Regex Comparison

• For leaf configurations, you can define the value to be a regular expression. When running a compliance report, the compliance engine will try to match the regular expression with the configuration on the device.
• This comparison will also run for Tree Variables that have 'pattern' selected.
• When you submit a compliance fix for an error, including a regular expression, a form will display asking the user to input the desired leaf value.

Using Regex for Key Comparison

Similar to other leaf values, the Golden Config application allows a user to mark the keys in config/rules as regular expressions. Optionally, Tree Variables set to regular expressions can be applied to a rule as well.

To use a regular expression pattern for key comparison:

1. Hover over the field. A cog icon will appear to the right.
2. Click the icon.
3. Select the Regex radio button.
4. Click SUBMIT.

Marking the config keys as regular expression is not the same as marking a normal field. When a user marks a key field as regular expression it not only evaluates the value of one element but it evaluates all corresponding list elements that are set for the device.

Any list item that has a key value matching the defined regular expression is considered valid. Moreover, if the field is marked as a regular expression and a regular expression for IP address is given, then any list item for peer-list that has an IP address as its name is considered valid.

Special Configuration Scenarios

Compound Keys

Be careful when marking the keys as regular expressions, especially when the configuration has compound keys.

• If one key is marked as regular expression and the other one is a string, then the compliance engine (Prospector) will consider valid any configuration that has a value matching the first key regular expression as well as any configuration that has a value equal to the string defined for the second key.

• For the configuration in the figure below, the following would be valid device configurations:

  • Line vty 0 4
  • Line vty 1 4
  • Line vty 3 4
  • Line vty 4 4

Conflicting Configurations

You may encounter situations with a list where a key is marked as regex and then for the same list another key is defined with a string value. In these situations, it is imperative the keys do not conflict. Incorrect definition of keys and regular expressions may lead to errors. If you encounter this situation, remove one of the keys.

Assume a device has a config like the example shown in the figure below:

• The first rule with key values [0-4] and [5-8] is marked as regex. The second rule with key values of 2 and 6 is marked as a string.
• Line vty 2 6
• Speed 96000
• With these rules, the device may never pass validation.
  • Validation would fail on the first rule because the speed does not match the regex.
  • If the transmit speed value is 9600 then it would fail on the second rule because it does not match the string.

Defining Generic Configurations (Advantage)

The constraint or behavior defined in the Conflicting Configurations section of this user guide can also be seen as an advantage to define generic configurations in certain list items. This will allow you to define configurations specific to the list item in separate rules.

In the figure below, the first rule states that for all configurations that have keys in the range [0-4] and [5-8] the authorization parameters should be set to default. For the second rule where the key values are specifically 2 and 6, also expect to have the transmit speed set to 9600.

Managing Devices

From the main screen view, you can attach devices to a selected node.

1. Click the Add Devices tab.
2. Select the checkbox next to the devices you want to add/remove.
3. Click ADD DEVICE LINKS (bottom left corner).

Once devices have been added to a node, the tree view will display the number of linked devices on the top right corner of the node.

Compliance Reporting

The Golden Configuration application includes the ability to run compliance reports and remediation tasks on devices attached to the nodes created in the Golden Config application.

Compliance Report Preview

There are two ways to run compliance reports from the list view on the main screen:

1. Click the Start (right arrow) icon to the right of any configuration tree in the list. Golden Config will run a Compliance Report on all nodes within that tree for all devices.
2. Click the Report (paper) icon to the right of the Start icon. The application will render a table with details about each node in the tree, including number of devices linked, number of rules, and the last compliance report that was run.

Note: Errors cannot be resolved in the Compliance Report preview. You can, however, resolve errors in reports run from the Compliance interface within selected nodes.

Running Compliance Reports

In the main view for each node:

1. Click the Compliance tab to show the number of devices attached to the selected node.
2. Select the checkbox next to the node(s).
3. Click the RUN button (top right) to run a compliance report on all devices linked to the node.
   • A notification will display the results (success/failure).
4. View the report under the Compliance tab for the selected node.

Compliance Report Details

Use the information in this section to view a detailed compliance report and fix compliance errors.

Fix Compliance Errors

To fix compliance errors:

1. Go to the Actions column.
2. Click the Preview (eye) icon to the right of the device.
3. Select the errors you want to automatically fix.
4. Click the FIX button. This will commit a dry run with the proposed changes and provide the native output from NSO.
5. Click the FIX button again if the dry run results are correct. This will commit the changes.

View Report Updates

After completing the fixes:

1. Click RUN to re-run the compliance report.

2. View the updated report.

   • The updated report provides a Device/Leaf History graph of compliance scores over time.

Using Remediation Workflow

The Golden Configuration application also allows users to fix compliance on devices using a remediation workflow. Workflow jobs can be created for all devices from the Compliance tab in the node view.

Defining a Workflow

Golden Config and Smart Template APIs are available in the workflow as manual and automatic tasks. A user can create a workflow using these tasks and attach the workflow to a tree.

The following tasks are available in the workflow engine:

• Run compliance report for a device.
• Obtain the latest device report.
• Display errors associated with a device in a tree.
• Display form for filling out values for regex errors.
• Dry run compliance fix.
• View dry run results.
• Provision changes.
• Auto select all errors from a report.
• Add and remove devices to a node.
• Run Tree reports, Node reports and any selected reports.
• Get the Smart Template instance for errors.
• View the compliance history of a device.
• Apply workflow template variables to a tree or node.
• Get the current Tree Variables.
• Update the Tree Variables and the resulting model of the config node.

To run a remediation workflow attached to a tree:

1. Select all devices to fix.
2. Select the REQUEST FIX button at the bottom of the Compliance tab page.